.\"
.\"  Copyright (c) 1998 Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.\" Copyright 2023 Oxide Computer Company
.Dd January 23, 2023
.Dt TD_THR_GETGREGS 3C_DB
.Os
.Sh NAME
.Nm td_thr_getgregs ,
.Nm td_thr_setgregs ,
.Nm td_thr_getfpregs ,
.Nm td_thr_setfpregs ,
.Nm td_thr_getxregsize ,
.Nm td_thr_getxregs ,
.Nm td_thr_setxregs
.Nd reading and writing thread registers in libc_db
.Sh LIBRARY
.Lb libc_db
.Sh SYNOPSIS
.In proc_service.h
.In thread_db.h
.Ft td_err_e
.Fo td_thr_getgregs
.Fa "const td_thrhandle_t *th_p"
.Fa "prgregset_t gregset"
.Fc
.Ft td_err_e
.Fo td_thr_setgregs
.Fa "const td_thrhandle_t *th_p"
.Fa "prgregset_t gregset"
.Fc
.Ft td_err_e
.Fo td_thr_getfpregs
.Fa "const td_thrhandle_t *th_p"
.Fa "prfpregset_t *fpregset"
.Fc
.Ft td_err_e
.Fo td_thr_setfpregs
.Fa "const td_thrhandle_t *th_p"
.Fa "prfpregset_t *fpregset"
.Fc
.Ft td_err_e
.Fo td_thr_getxregsize
.Fa "const td_thrhandle_t *th_p"
.Fa "int *xregsize"
.Fc
.Ft td_err_e
.Fo td_thr_getxregs
.Fa "const td_thrhandle_t *th_p"
.Fa "prxregset_t *xregset"
.Fc
.Ft td_err_e
.Fo td_thr_setxregs
.Fa "const td_thrhandle_t *th_p"
.Fa "prxregset_t *xregset"
.Fc
.Sh DESCRIPTION
These functions read and write the register sets associated with thread
.Fa th_p .
The
.Fn td_thr_getgregs
and
.Fn td_thr_setgregs
functions get and set, respectively, the general registers of thread
.Fa th_p .
The
.Fn td_thr_getfpregs
and
.Fn td_thr_setfpregs
functions get and set, respectively, the thread's floating point register set.
.Pp
The
.Fn td_thr_getxregsize
function returns in
.Fa *xregsize
the size of the
architecture-dependent extra state registers.
The
.Fn td_thr_getxregs
and
.Fn td_thr_setxregs
functions get and set, respectively, those extra state registers.
The buffer passed to
.Fn td_thr_getxregs
must be at least the size indicated by
.Fn td_thr_getxregsize .
This size must not be assumed and may change between processes.
Failure to do so, will result in the system overwriting memory.
Not all platforms implement extended registers.
When they are not implemented, these functions return
.Dv TD_NOXREGS .
.Sh RETURN VALUES
The
.Fn td_thr_getgregs ,
.Fn td_thr_setgregs ,
.Fn td_thr_getfpregs ,
.Fn td_thr_setfpregs ,
.Fn td_thr_getxregsize ,
.Fn td_thr_getxregs ,
and
.Fn td_thr_setxregs
functions return one of the following values:
.Bl -tag -width Ds
.It Dv TD_OK
The call completed successfully.
.It Dv TD_BADTH
An invalid thread handle was passed in.
.It Dv TD_DBERR
A call to one of the imported interface routines failed.
.It Dv TD_NOFPREGS
Floating point registers could not be read or written because the architecture
does not have such registers.
.It Dv TD_NOXREGS
Architecture-dependent extra state registers could not be read or written,
because the architecture does not have such registers.
.It Dv TD_ERR
A
.Sy libc_db
internal error occurred.
.El
.Sh MT-LEVEL
.Sy Safe
.Sh SEE ALSO
.Xr libc_db 3LIB ,
.Xr attributes 7
